home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 23 / CU Amiga - Super CD-ROM 23 (June 1998).iso / CreatingGames / Utilities / E / PlayTHX / thx-play.doc < prev    next >
Encoding:
Text File  |  1997-10-07  |  7.9 KB  |  302 lines
  1. Emodules:Tools/thx-play.m  (and  Emodules:Tools/thx-play_020.m  --  a 68020
  2. optimised version, not 68000 compatible)
  3.  
  4. E interface to the THX2 player by Martin Wodok (Dexter/Abyss).
  5.  
  6. Note:  You need to read a THX module in from disk or INCBIN it, this is not
  7. one  of the functions in thx-play.m. You should load it into PUBLIC memory,
  8. it  does  not  have to be CHIP memory. The module 'tools/file' is handy for
  9. loading files from disk.
  10.  
  11. Example  source  (see src/PlayTHX.e and src/PlayTHX_gui.e for more detailed
  12. example):
  13.  
  14. MODULE 'tools/thx-play','tools/file'
  15. PROC main()
  16.   DEF mod,vol
  17.   IF mod:=loadfile(arg)
  18.     IF thxInit(mod)=0
  19.       thxPlay()
  20.       REPEAT; WaitTOF(); UNTIL CtrlC() OR thxSongEnded()
  21.       thxStop()
  22.  
  23.       thxFree()
  24.     ENDIF
  25.     freefile(mod)
  26.   ENDIF
  27. ENDPROC
  28.  
  29.  
  30. Functions:
  31. -----------------------------------------------------------------------------
  32.  
  33. NAME
  34.   thxInit() -- initialise player and module.
  35.  
  36. SYNOPSIS
  37.   error=thxInit(moduleptr)
  38.  
  39. FUNCTION
  40.   Initialises the player (if needed) and initializes the module. You may also
  41.   call thxInit(0) to initialise the player but not the module. Does not start
  42.   to  play  the module until you call thxPlay(). You must call this each time
  43.   you  want  to  play a different module. The allocations made for the player
  44.   are made only the first time you call thxInit(), no matter how many modules
  45.   you want. If allocations fail, they will be automatically freed.
  46.  
  47. INPUTS
  48.   module - pointer to a THX module or 0
  49.  
  50. RESULT
  51.   error - 0 means all went OK, any other value means something FAILED.
  52.  
  53. SEE ALSO
  54.   thxFree(), thxPlay()
  55.  
  56. -----------------------------------------------------------------------------
  57.  
  58. NAME
  59.   thxFree() -- free resources held by player.
  60.  
  61. SYNOPSIS
  62.   void thxFree()
  63.  
  64. FUNCTION
  65.   Stops  any  THX  module playing and frees resources used by the player. You
  66.   can call this whether thxInit() suceeded or not.
  67.  
  68. SEE ALSO
  69.   thxInit()
  70.  
  71. -----------------------------------------------------------------------------
  72.  
  73. NAME
  74.   thxPlay() -- start playing the song.
  75.  
  76. SYNOPSIS
  77.   void thxPlay()
  78.  
  79. FUNCTION
  80.   Starts  playing  the  module.  If  the  module has just been initialised or
  81.   stopped,  or the subsong has just been changed, then play will start at the
  82.   beginning  of  the  song/subsong. Otherwise, it will continue from where it
  83.   was paused.
  84.  
  85. SEE ALSO
  86.   thxStop(), thxPause()
  87.  
  88. -----------------------------------------------------------------------------
  89.  
  90. NAME
  91.   thxStop() -- stop playing a song/module.
  92.  
  93. SYNOPSIS
  94.   void thxStop()
  95.  
  96. FUNCTION
  97.   Stops the module. Can be restarted from the beginning again with thxPlay().
  98.   If  you  call this, you can free the memory used by your thx module without
  99.   calling   thxFree()  which  has  the  unpleasant  effect  of  requiring  to
  100.   recalculate all the filters if you call thxInit() again.
  101.  
  102. SEE ALSO
  103.   thxPlay(), thxFree()
  104.  
  105. -----------------------------------------------------------------------------
  106.  
  107. NAME
  108.   thxPause() -- pause play of a song.
  109.  
  110. SYNOPSIS
  111.   void thxPause()
  112.  
  113. FUNCTION
  114.   Pauses the playing module. Call thxPlay() to continue play again.
  115.  
  116. SEE ALSO
  117.   thxPlay()
  118.  
  119. -----------------------------------------------------------------------------
  120.  
  121. NAME
  122.   thxWind() -- wind the song forward or back.
  123.  
  124. SYNOPSIS
  125.   void thxWind(direction)
  126.  
  127. FUNCTION
  128.   Advances  forward  or  backwards  through the song by a specified number of
  129.   positions.  Please use the value 1 to skip forward and -1 to skip back, for
  130.   future compatibility.
  131.  
  132. INPUTS
  133.   direction - if positive, winds on to the next position.
  134.               if negative, winds back to the previous position,
  135.               if 0, ignored.
  136.  
  137. NOTE
  138.   Be  wary of stepping beyond the end of a song. Also note this function only
  139.   takes effect once a frame or so.
  140.  
  141. SEE ALSO
  142.  
  143. -----------------------------------------------------------------------------
  144.  
  145. NAME
  146.   thxSetSong() -- set song to be played.
  147.  
  148. SYNOPSIS
  149.   thxSetSong(song)
  150.  
  151. FUNCTION
  152.   Sets  which  song  to  play,  if a module contains more than one song. Most
  153.   modules  only  contain one song, but some modules contain sub-songs as well
  154.   as  the  main one. You can use this function to specify which one should be
  155.   played.  If  you call this function and there is already a song playing, it
  156.   will be stopped first.
  157.  
  158. INPUTS
  159.   song - 0 to set the main song to be played, any other number will change to
  160.          that subsong, if it exists. Otherwise, no change will be made (other
  161.          than the stoppage).
  162.  
  163. NOTE
  164.   It is up to you to start playing the module again.
  165.  
  166. SEE ALSO
  167.   thxGetNumSongs()
  168.  
  169. -----------------------------------------------------------------------------
  170.  
  171. NAME
  172.   thxGetNumSongs() -- get number of subsongs.
  173.  
  174. SYNOPSIS
  175.   songs=thxGetNumSongs()
  176.  
  177. FUNCTION
  178.   Returns  the  number  of  subsongs  in  the module, if any. You can use the
  179.   thxSetSong() function to play one of the subsongs, if that's possible.
  180.  
  181. RESULT
  182.   songs - 0 if there are no subsongs (only the main song),  otherwise returns
  183.           the number of subsongs.
  184.  
  185. SEE ALSO
  186.   thxSetSong()
  187.  
  188. -----------------------------------------------------------------------------
  189.  
  190. NAME
  191.   thxSetVolume() -- set master volume.
  192.  
  193. SYNOPSIS
  194.   thxSetVolume(volume)
  195.  
  196. FUNCTION
  197.   Sets the master volume. Does not stop play.
  198.  
  199. INPUTS
  200.   volume - from 0 (silent) to 64 (loudest)
  201.  
  202. NOTE
  203.   This function can take up to two frames to take an audible effect.
  204.   If song is paused, will not take effect until unpaused.
  205.  
  206. SEE ALSO
  207.   thxGetVolume()
  208.  
  209. -----------------------------------------------------------------------------
  210.  
  211. NAME
  212.   thxGetVolume() -- get master volume.
  213.  
  214. SYNOPIS
  215.   volume=thxGetVolume()
  216.  
  217. FUNCTION
  218.   Gets the current setting of the master volume. Does not stop play.
  219.  
  220. RESULT
  221.   volume - current volume setting from 0 (silent) to 64 (loudest)
  222.  
  223. SEE ALSO
  224.   thxSetVolume()
  225.  
  226. -----------------------------------------------------------------------------
  227.  
  228. NAME
  229.   thxSyncByte() -- get sync byte value.
  230.  
  231. SYNOPIS
  232.   value=thxSyncByte()
  233.  
  234. FUNCTION
  235.   Gets the current setting of the 'external timing' byte, which can be set to
  236.   any  byte  value  at any moment in time during play of the song BY the song
  237.   itself, using the 8 command in the tracker. It's there to allow you to mark
  238.   specific  events  in  the  music  with the 8 command and a value, then wait
  239.   until  calling thxSyncByte() returns that value. The returned value doesn't
  240.   change until another 8 command in the song changes it.
  241.  
  242. NOTE
  243.   Be very careful not to busy-wait on a new value if there is the possibility
  244.   the song is paused or not playing.
  245.  
  246. RESULT
  247.   value - current value of the sync byte.
  248.  
  249. SEE ALSO
  250.  
  251. -----------------------------------------------------------------------------
  252.  
  253. NAME
  254.   thxSongEnded() -- detect if song has ended.
  255.  
  256. SYNOPIS
  257.   ended=thxSongEnded()
  258.  
  259. FUNCTION
  260.   Returns  nonzero  value if the player has detected the end of a song and is
  261.   now looping.
  262.  
  263. NOTE
  264.   The detection of songend is crap (sorry Dexter :^)
  265.  
  266. RESULT
  267.   value - nonzero if song is now looping, zero otherwise.
  268.  
  269. SEE ALSO
  270.   thxSignalEnd()
  271.  
  272. -----------------------------------------------------------------------------
  273.  
  274. NAME
  275.   thxSignalEnd() -- Signal() when song ends.
  276.  
  277. SYNOPIS
  278.   thxSignalEnd(signals)
  279.  
  280. FUNCTION
  281.   Asks THX to send the signals you specify back to you when the song ends. If
  282.   songend occurs and the signal is sent, it will not be sent again unless you
  283.   call  thxSignalEnd()  again  to reload the trigger. The signal will also be
  284.   cancelled   if   you   call   thxStop()  directly,  or  indirectly  through
  285.   thxSetSong()  or  thxFree().  You  may call this function at any time, even
  286.   when  the  player  is not initialised, or while a song is playing. The task
  287.   you  call  it  from  is stored, so don't call it from asynchroneous threads
  288.   that may disappear before songend is reached.
  289.  
  290. NOTE
  291.   The detection of songend is crap (sorry Dexter :^)
  292.  
  293. INPUT
  294.   signals - a 32bit set of signals, eg (SIGBREAKF_CTRL_C OR SIGBREAKF_CTRL_D)
  295.             to be sent back to calling task when songend occurs.
  296.  
  297. SEE ALSO
  298.   thxSongEnded(), exec.library/Signal()
  299.  
  300. -----------------------------------------------------------------------------
  301.  
  302. Kyzer/CSG, 8-Oct-1997